home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan 2 / Opus 5 - Magellan 2.iso / DOpus_SDK_5.5 / docs / notify.doc < prev    next >
Text File  |  1996-09-05  |  7KB  |  201 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/AddNotifyRequest
  4. dopus5.library/RemoveNotifyRequest
  5. dopus5.library/ReplyFreeMsg
  6. dopus5.library/SetNotifyRequest
  7. dopus5.library/AddNotifyRequest               dopus5.library/AddNotifyRequest
  8.  
  9.     NAME
  10.         AddNotifyRequest - add a request to Opus's notify chain
  11.  
  12.     SYNOPSIS
  13.         AddNotifyRequest(type, userdata, port)
  14.                           D0      D1      A0
  15.  
  16.         APTR AddNotifyRequest(ULONG, ULONG, struct MsgPort *);
  17.  
  18.     FUNCTION
  19.         Opus keeps track of several different system events, and this routine
  20.         allows you to request notification on them.
  21.  
  22.         The events currently available for notification:
  23.  
  24.             DN_WRITE_ICON      - an icon is written to disk
  25.             DN_APP_ICON_LIST   - an AppIcon is added or removed
  26.             DN_APP_MENU_LIST   - an AppMenuItem is added or removed
  27.             DN_CLOSE_WORKBENCH - CloseWorkbench() has been called
  28.             DN_OPEN_WORKBENCH  - OpenWorkbench() has been called
  29.             DN_RESET_WORKBENCH - the workbench screen has been closed and
  30.                                  re-opened
  31.             DN_DISKCHANGE      - a disk has been inserted or removed
  32.             DN_DOS_ACTION      - a DOS event has occurred. In Opus 5.5,
  33.                                  these messages are only available if the
  34.                                  dopus/DOSPatch environment variable is set.
  35.             DN_REXX_UP         - the ARexx process has been started.
  36.  
  37.         Several Opus events are also available for notification:
  38.  
  39.             DN_OPUS_START      - Opus has started
  40.             DN_OPUS_QUIT       - Opus has quit
  41.             DN_OPUS_HIDE       - Opus has been hidden
  42.             DN_OPUS_SHOW       - Opus has been revealed
  43.  
  44.         When an event occurs that you have requested notification for, a
  45.         DOpusNotify message is sent to your message port. The message
  46.         structure is defined as follows:
  47.  
  48.             dn_Msg      - Exec message header
  49.  
  50.             dn_Type     - Event type
  51.  
  52.             dn_UserData - the userdata you supplied to AddNotifyRequest()
  53.  
  54.             dn_Data     - data specific to the type of event
  55.  
  56.             dn_Flags    - flags specific to the type of event
  57.  
  58.             dn_Fib      - a FileInfoBlock for some types of event
  59.  
  60.             dn_Name     - pathname specific to the type of event
  61.  
  62.  
  63.         The event-specific fields are used in the following way:
  64.  
  65.             DN_WRITE_ICON
  66.             -------------
  67.                 dn_Data  - NULL
  68.                 dn_Flags - if DNF_ICON_REMOVED is set, icon was deleted
  69.                 dn_Fib   - NULL
  70.                 dn_Name  - full pathname of icon
  71.  
  72.             DN_APP_ICON_LIST
  73.             ----------------
  74.                 dn_Data  - pointer to the AppIcon added or removed
  75.                 dn_Flags - if DNF_ICON_REMOVED is set, icon was removed
  76.                            if DNF_ICON_CHANGED is set, the icon image
  77.                            was changed
  78.                 dn_Fib   - NULL
  79.                 dn_Name  - NULL
  80.  
  81.             DN_APP_MENU_LIST
  82.             ----------------
  83.                 dn_Data  - pointer to the AppMenuItem added or removed
  84.                 dn_Flags - if DNF_ICON_REMOVED is set, item was removed
  85.                 dn_Fib   - NULL
  86.                 dn_Name  - NULL
  87.  
  88.             DN_DISKCHANGE
  89.             -------------
  90.                 dn_Data  - disk units the change occurred in (bits 0-3
  91.                            represent units 0-3)
  92.                 dn_Flags - which units have disks in them (bits 0-3
  93.                            represent units 0-3)
  94.                 dn_Fib   - NULL
  95.                 dn_Name  - NULL
  96.  
  97.             DN_DOS_ACTION
  98.             -------------
  99.                 dn_Data  - NULL
  100.                 dn_Flags - which DOS action occurred (see <dopus/notify.h>)
  101.                 dn_Fib   - FileInfoBlock with file information. This is
  102.                            supplied for all actions except Delete.
  103.                 dn_Name  - full pathname of file involved
  104.  
  105.     INPUTS
  106.         type - type of events you want to be notified of. One request can
  107.                ask for multiple events. See <dopus/notify.h> for the full
  108.                list.
  109.  
  110.         userdata - a user-defined data field that is passed in any notify
  111.                    messages.
  112.  
  113.         port - message port to send notification messages to.
  114.  
  115.     NOTES
  116.         Most notification messages are sent "reply free", meaning you must
  117.         use the ReplyFreeMsg() call to reply to them. Otherwise, the
  118.         message memory will be lost.
  119.  
  120.     RESULT
  121.         Returns a notify handle which you use to remove the request.
  122.  
  123.     SEE ALSO
  124.         RemoveNotifyRequest(), SetNotifyRequest()
  125.  
  126. dopus5.library/RemoveNotifyRequest         dopus5.library/RemoveNotifyRequest
  127.  
  128.     NAME
  129.         RemoveNotifyRequest - remove a notification request
  130.  
  131.     SYNOPSIS
  132.         RemoveNotifyRequest(request)
  133.                               A0
  134.  
  135.         void RemoveNotifyRequest(APTR);
  136.  
  137.     FUNCTION
  138.         Removes a notify request that was added with AddNotifyRequest().
  139.  
  140.     INPUTS
  141.         request - request to remove
  142.  
  143.     RESULT
  144.         The request is removed. You will receive no more notifications for
  145.         that request. Once you have removed the request you should check
  146.         your message port for outstanding messages and reply to them.
  147.  
  148.     SEE ALSO
  149.         AddNotifyRequest()
  150.  
  151. dopus5.library/ReplyFreeMsg                       dopus5.library/ReplyFreeMsg
  152.  
  153.     NAME
  154.         ReplyFreeMsg - reply or free a message
  155.  
  156.     SYNOPSIS
  157.         ReplyFreeMsg(msg)
  158.                       A0
  159.  
  160.         void ReplyFreeMsg(struct Message *);
  161.  
  162.     FUNCTION
  163.         If the message has a valid ReplyPort, this function simply passes it
  164.         through to ReplyMsg(). If the message has no reply port set, this
  165.         function calls FreeVec() on the message to free it.
  166.  
  167.     INPUTS
  168.         msg - message to reply or free
  169.  
  170.     NOTES
  171.         Most Opus notification messages are sent "reply free", meaning you
  172.         MUST use this function to reply to them or the memory will be lost.
  173.  
  174.     SEE ALSO
  175.         AddNotifyRequest()
  176.  
  177. dopus5.library/SetNotifyRequest               dopus5.library/SetNotifyRequest
  178.  
  179.     NAME
  180.         SetNotifyRequest - change notification events
  181.  
  182.     SYNOPSIS
  183.         SetNotifyRequest(request, new_type, mask)
  184.                            A0        D0      D1
  185.  
  186.         void SetNotifyRequest(APTR, ULONG, ULONG);
  187.  
  188.     FUNCTION
  189.         This routine changes the type of events that an existing notification
  190.         request is interested in.
  191.  
  192.     INPUTS
  193.         request - notification request to change
  194.         new_type - the new event flags to receive notification about
  195.         mask - mask of event flags to change (any events not specified in the
  196.                mask field will not be modified)
  197.  
  198.     SEE ALSO
  199.         AddNotifyRequest()
  200.  
  201.